home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 1.iso / ARGONET / PD / FILER / TARSRC.SPK / ReadMe < prev    next >
Text File  |  1995-02-24  |  17KB  |  481 lines
  1. tar - tape archive, version 1.2b, written for the Archimedes by
  2.  
  3.                     Frank Lancaster, 25-Jan-1995
  4.  
  5. Bug reports and comments may be sent as e-mail to: fl@tools.de
  6. Paper Mail: Frank Lancaster
  7.             Tools GmbH
  8.             Adolfstr. 5
  9.             53111 Bonn
  10.             Germany
  11.  
  12.  
  13. This programme is public domain. You may copy it freely, provided
  14. you do not charge ANYTHING for its distribution.
  15.  
  16.  
  17. Table of Contents
  18. -----------------
  19.  1. Introduction
  20.  2. Installation
  21.  3. Usage
  22.  4. Normal Files As Archives
  23.  5. Hard Disc Backup
  24.  6. Compression
  25.  7. The List File
  26.  8. UNIX Compatibility
  27.  9. Raw disc dumping
  28. 10. Remote tape devices
  29. 11. History
  30.  
  31.  
  32.  
  33. 1. Introduction
  34. ---------------
  35. This version of tar is derived from the UNIX tar utility. Its main use
  36. is as a hard disk backup programme. It also comes in very handy when
  37. transferring files from or to UNIX. The name "tape archive" is misleading but
  38. historical. On the Archimedes archives are ordinary files on any
  39. file-system (adfs, scsi, dosfs, etc.). Multiple disc archives are supported,
  40. now also as ordinary files. Disk archives in ADFS D/E/F/L or MS-DOS (double-
  41. sided, 9/18 sectors) format dumped to raw disks are supported.
  42.  
  43.  
  44.  
  45. 2. Installation
  46. ---------------
  47. Before using the programme set the system variable "tar$scrap" to the
  48. name of a temporary scrap file which should only be used by tar,
  49. for example "adfs::4.$.tmp.scrap". The leaf name must not be longer than
  50. 8 characters, another 2 ("/Z") are added if compression is used.
  51. This file will only be used if compression is enabled.
  52. If compression is used tar requires a compression programme (the defualt is
  53. to call compress), which handles compression and decompression. Normally
  54. this should be accessable via the system variable Run$Path, but you can
  55. customize the compression and decompression commands with the two system
  56. variables tar$compress and tar$decompress (see below "compression").
  57. The system variable tar$filetype is used as file type for tar files. If
  58. it is not set, file type FFD (data) is used.
  59.  
  60.  
  61.  
  62. 3. Usage
  63. --------
  64. The programme should be called from the command line interpreter as it
  65. requires parameters.
  66.  
  67. tar [-]Commands[Options] ARCHIVE [LIST] [BLKS] [LEN] [-C DIR] file1 file2 ...
  68.  
  69. Commands:
  70.      c           create a new archive
  71.      r           append files to end of archive
  72.      t           list the contents of an archive
  73.      x           extract files from an archive
  74.  
  75. Options:
  76.      b BLKS      blocking factor BLKS (block size = BLKS x 512 bytes)
  77.      e LENGTH    maximum length of extension to use in UNIX file names
  78.      f ARCHIVE   read/write archive from file ARCHIVE (mandatory)
  79.      i           ignore checksum errors and blocks of zeros (normally EOF)
  80.      l [LIST]    read list of files from file LIST or !tarlist as default
  81.      m           do not extract date and times of files
  82.      p           convert '!' in RISC OS names to '_' in UNIX names
  83.      s           swap extension in filename
  84.      v           verbosely list what files we process
  85.      w           ask for confirmation
  86.      z           compress files before archiving
  87.      B           re-block as we read
  88.      C DIR       change to directory DIR
  89.      E           '.' in UNIX names will be converted to '/'
  90.      F           format disk in drive 0 (multiple volumes & E-format only)
  91.      G           use GNU tar multiple volume archiving
  92.      M           use multiple volume archiving
  93.      L LEN       maximum file/directory name is LEN when extracting (default 10)
  94.      O           do not prompt for confimation when formating or overwriting disk
  95.      P           use RISC OS 3 path canonicalise instead of own routine
  96.      Q           quit immediately if error occurs, do not prompt for action
  97.      S           swap extensions in whole path
  98.      T           file types appended to names as with RISC-OS NFS
  99.      U           UNIX archive (no Archimedes extensions)
  100.      V           very verbose mode: also display files that are not extracted
  101.      X           add RISC OS file type as extension to file name in archive
  102.      Z           convert UNIX '.Z' to compress extension (default '/Z') when extracting
  103.  
  104.  
  105. You must specify an archive file on the command line with the 'f' option.
  106. The path names of the archived files are stored as specified on
  107. the command line. Using the 'v' (verbose) option will list the path names
  108. stored as the archive is created. Normally you shouldn't specify the absolute
  109. path names, as you may want to extract the files to an other directory.
  110.  
  111.  
  112.  
  113. 4. Normal Files As Archives
  114. ---------------------------
  115. Here the use of tar is identical to the UNIX usage. The file name of an
  116. archive must always be supplied with the 'f' option. To create an archive
  117. use the 'c' option:
  118.  
  119. tar cvf myarc file1 file2 file3
  120.  
  121. This will create an archive 'myarc' in the current directory which contains
  122. the files 'file1', 'file2' and 'file3'. I always recommend using the 'v'
  123. option with every command, this gives more information on what is happening.
  124.  
  125. You can use path names with the archives and files specified:
  126.  
  127. tar cvf adfs::4.tmp.myarc adfs::5.file1 adfs::4.src.file2
  128.  
  129. To list the contents of an archive use the 't' command:
  130.  
  131. tar tvf myarc
  132.  
  133. To extract files from an archive use the 'x' command:
  134.  
  135. tar xvf myarc
  136.  
  137. This command will extract all files in the archive. If you only want certain
  138. files, you can specify them after the archive name:
  139.  
  140. tar xvf myarc file1 file2
  141.  
  142.  
  143.  
  144. 5. Hard disc backup
  145. -------------------
  146. This actually isn't very different from normal archiving. The main difference
  147. is that archive files are of course written to floppy discs and that they
  148. can be split across several discs. The command:
  149.  
  150. tar cvMf :0.backup :4.*
  151.  
  152. will backup all files on the hard disk :4 onto floppy disk :0 in the
  153. file 'backup'. If the archive requires more than one floppy disc, you will
  154. be prompted for more discs, which will contain further files also called
  155. 'backup'. They contain a header which supplies identification of the disc
  156. number so that 'tar' will be able to determine the disc sequence when
  157. extracting.
  158.  
  159. It would be better to go to the root directory of the hard disc and to use
  160. the following command:
  161.  
  162. tar cvMf :0.backup *
  163.  
  164. This will store the path names without the drive name, so you could extract
  165. them onto a different hard disk.
  166.  
  167. The command:
  168.  
  169. tar tvf :0.backup
  170.  
  171. will list the contents of an archive on floppy disc :0. If the archive was
  172. split across several discs, tar will prompt for further discs when finished
  173. listing one.
  174.  
  175. The command:
  176.  
  177. tar xvf :0.backup
  178.  
  179. will extract all files on floppy disc :0 in the file 'backup'. If the file,
  180. which is being extracted, already exists, tar will overwrite it without any
  181. warning.
  182.  
  183.  
  184.  
  185. 6. Compression
  186. --------------
  187. With the 'z' option files can be compressed before being written to an archive.
  188. For compression the standard UNIX utility compress is used. Due to the patent
  189. problems with compress the program is not supplied anymore with the tar programme.
  190. The system variable tar$scrap is used for temporary storage.
  191. If you are backing up a complete hard disc and have enough memory you should
  192. use a RAM disc for the scrap file, and the compress programme should also be
  193. copied onto the RAM disc. You can use different programmes for
  194. compression and decompression if you set the tar$compress and tar$decompress
  195. system variables. The default settings are:
  196.  
  197.   tar$compress          compress < %1 > %2
  198.   tar$decompress        compress -d < %1 > %2
  199.  
  200. Most compression programmes add a suffix to the compressed file. The UNIX
  201. compress programme adds '/Z'. If a compression programme that you want to use,
  202. uses a different suffix, you can set the system variable 'tar$compress$extension'.
  203.  
  204. When writing a file 'TresImp' to an archive the compress command will expand to:
  205.  
  206.   compress < TresImp > Scrap-Z
  207.  
  208. The %1 parameter is substituted with the file name and %2 is substituted with
  209. the scrap file name.
  210.  
  211. The decompress command, when extracting the file, will expand to:
  212.  
  213.   compress -d < Scrap-Z > TresImp
  214.  
  215. So if you have a compression programme 'squash' and a decompression programme
  216. 'expand', which take two parameters and don't use I/O redirection, set the
  217. variables to:
  218.  
  219.   tar$compress          squash %1 %2
  220.   tar$decompress        expand %1 %2
  221.  
  222. You can also specify absolute paths in these variables, e.g. when the
  223. compression programme is on the RAM disc:
  224.  
  225.   tar$compress          ram:$.compress < %1 > %2
  226.   tar$decompress        ram:$.compress -d < %1 > %2
  227.  
  228. Compressed files are automatically detected when extracting. A verbose listing
  229. of the archive also shows the compression percentage.
  230.  
  231. NOTE: The 'z' option is intended for hard disc backups, so that they can be
  232. compressed while being created. If you are creating a normal archive file which
  233. will not be split, it is more efficient to compress the tar archive after
  234. it has been created. To do this, use the compress programme:
  235.  
  236. tar cvf myarc files...
  237. compress myarc
  238.  
  239. You will have to decompress the archive before extracting file form it.
  240.  
  241.  
  242.  
  243. 7. The List File
  244. ----------------
  245. The command:
  246.  
  247. tar l tarlist
  248.  
  249. will read file names and options from the file 'tarlist' instead of the
  250. command line, if any file names are given they will be ignored, options
  251. on the command line are overridden by options specified in the 'tarlist'
  252. file. The 'tarlist' file may contain empty lines, which are ignored, lines
  253. with one file name, and lines starting with a period followed by one
  254. command or option or a blank and a comment. For example:
  255.  
  256.  
  257. . tar archive definition file (this is a comment, note blank after the period)
  258.  
  259. .c create command (stuff after .c is ignored)
  260. .v verbose option (stuff after .v is ignored)
  261. .f :0.backup (archive file name)
  262. .z compress option ( " )
  263. .b 400 blocking factor (stuff after 400 is ignored)
  264.  
  265. . file names follow
  266.  
  267. !Boot
  268. Apps.*
  269. Games.*
  270.  
  271.  
  272. This example file can be found in the distributed tar archive. If no list file
  273. name is given on the command line '!tarlist' will be used as default.
  274.  
  275.  
  276.  
  277. 8. UNIX Compatibility
  278. ---------------------
  279. Another main use of the tar programme is as a file transfer programme between
  280. UNIX and RISC OS. Archives created with the 'U' option can be processed by
  281. UNIX tar programmes. The UNIX file system doesn't know anything about file
  282. types, so these will be lost when using the 'U' option. File permissions and
  283. date stamps are converted to UNIX format (this is always done, even if the
  284. 'U' option is not used, but tar will save the original RISC OS date stamps
  285. also if 'U' is not used. UNIX tar programmes which ignore extra information
  286. in the tar header will be able to process non-UNIX archives).
  287.  
  288. The RISC OS version of tar detects UNIX tar archives and converts file names to
  289. adfs. The 's' option can be used to swap the extension of a file:
  290.  
  291. RISC OS ---> UNIX:  c.test ---> test.c
  292. UNIX ---> RISC OS:  test.c ---> c.test
  293.  
  294. When converting from RISC OS to UNIX, tar will only regard directories as a file
  295. name extension if the directory name is shorter than the maximum file name
  296. extension length. This is 3 by default, but can be set with the 'e' option.
  297.  
  298. The 'Z' option converts the UNIX '.Z' suffix to a '-Z' suffix as used by the
  299. compress programme ( test.c.Z -> c.test-Z ).
  300.  
  301. The 'p' option can be used when creating a UNIX archive to translate a '!' at the
  302. beginning of a file name to '.'.
  303.  
  304. NOTE: UNIX tar archives do not support multiple disc archives! They also do not
  305.       support date stamps which are less than 1-Jan-1970.
  306.  
  307.  
  308.  
  309. 9. Raw disc dumping
  310. -------------------
  311. To transfer files directly via floppy disc to a UNIX machine, you will have to
  312. create a UNIX archive which is dumped on a raw disc, i.d. a disc that is
  313. formatted but which will not contain a directory structure. The most common
  314. disc format is the MS-DOS format (2 sides, 80 tracks, 9 sectors per track).
  315.  
  316. To create a raw disc archive use the special archive name 'floppy:'. Supply
  317. the drive number and format after the colon. For example:
  318.  
  319. tar cvf floppy:0E files...
  320.  
  321. will create a raw disc archive in drive 0 on a E-format disc.
  322.  
  323. tar cvf floppy:0M files...
  324.  
  325. will create a raw disc archive in MS-DOS 720K format. Most formats
  326. (D,E,F,H,L,M,N,Q) supported by the RISC OS disc floppy format command
  327. are supported by tar. The default format is E (this is the same as the
  328. D format for raw writing).
  329.  
  330. Disc should be formatted before dumping an archive on them.
  331.  
  332. On a UNIX machine a typical command to extract an archive from floppy disc
  333. could be:
  334.  
  335. tar xvf /dev/rfd0
  336.  
  337.  
  338.  
  339. 10. Remote Tape Devices
  340. -----------------------
  341. tar supports the remote tape device protocol (RMT) which is used
  342. with UNIX machines. If you have the TCP/IP suite from Acorn you
  343. can use tar to archive from your RISC OS machine to a tape device
  344. connected to a UNIX machine. The syntax for the archive name is:
  345.  
  346. RMT:user@machine:tapedevice
  347.  
  348. For example to create an archive:
  349.  
  350. tar cvf RMT:fl@leo:/dev/rst0 *
  351.  
  352. This feature has only been tested at one site, so if you have
  353. problems contact me.
  354.  
  355.  
  356. 11. History
  357. -----------
  358.  
  359. 1.2a/b:
  360.   - finally some RISC OS 3 stuff:
  361.       image files are now archived (as one file)
  362.       archiving to raw HD discs (ADFS F and MSDOS formats)
  363.       can use canonicalise routines for absolute path names ('P' option)
  364.         (this helps with NFS and other esoteric filing systems)
  365.   - now supports the remote tape archiving (RMT) protocol
  366.     use RMT:user@machine:tapedevice as archive-name
  367.   - 'G' option: gnu tar archiving (not implemented yet), only dearchiving works
  368.   - 'L' option for maximum RISC OS leafname length
  369.   - 'V' very verbose option in extract mode
  370.   - 'X' documentation was missing
  371.  
  372. 1.1o:
  373.   - Acorn tar file type &C46 is now used by default
  374.   - exit code is now 0 not 22 when writing archive
  375.   - tar sprite now for file type &C46
  376.  
  377. 1.1n
  378.   - extensions were not truncated when extracting from unix archives
  379.   - tar file type is now always used
  380.   - simple tar file sprite included in the distribution
  381.  
  382. 1.1m
  383.   - severe mess-up when truncating long unix path names corrected,
  384.     first file with directories in name which had to be created was not extracted!
  385.  
  386. 1.1l
  387.   - new 'X' option, add textual file type as extension in UNIX archives
  388.  
  389. 1.1k
  390.   - formatting is now done with *adfs:format 0 e y
  391.  
  392. 1.1j
  393.   - 'Q' option corrected, options are scanned before startup code
  394.      is performed
  395.  
  396. 1.1i
  397.   - 'T' option now works correctly with file types less than 0x100
  398.  
  399. 1.1h
  400.   - removed problems with startup-dir and archive on separate discs
  401.  
  402. 1.1g
  403.   - limit of 77 files in a directory removed
  404.   - programme now exits with Sys$ReturnCode != 0 on user interrupt
  405.     if writing an archive
  406.  
  407. 1.1f
  408.   - 'Q' option added: non-interactive mode
  409.   - 'T' option added: file type handling like RISC-OS NFS
  410.  
  411. 1.1e
  412.   - "-C" can now also be used when extracting
  413.  
  414. 1.1d
  415.   - 'M' option re-introduced, must be used for multiple disc archiving
  416.   - raw disc dumping now should be chosen with 'f' option and 'floppy:'
  417.     archive name
  418.   - prompt for confirmation when using raw disc archives,
  419.     'O' option disables confirmation
  420.   - improved 'i' option, better defective archive handling
  421.   - when creating UNIX archives, directory to file extension swapping
  422.     will only occur if 's' option is used
  423.   - 'p' option introduced, enables '!' to '.' translation
  424.   - 'F' option introduced, formats floppy in drive 0 to E-format,
  425.     intended for hard-disc backup
  426.   - new system variable tar$compress$extension enables further configuring
  427.     of the compression programme used.
  428.  
  429. 1.1a
  430.   - first release to 'comp.sys.acorn'
  431.     Now I can feel what international means...
  432.     (A tip of the magical hat to all Rush fans)
  433.   - multiple disc archiving changed, now consistent with normal use; archives
  434.     on multiple floppy discs are now ordinary files and are split into
  435.     several files on different discs; main problem was writing a
  436.     filing-system independent free-space routine (not all filing systems are
  437.     FileCore based!)
  438.   - tar$filetype introduced; when set use value as FileType for tar files,
  439.     maybe Acorn could supply a tar file type; this would be mandatory for
  440.     a desktop version
  441.   - dangerous bug with tar$scrap set to directory removed; used to delete
  442.     directory recursively, now produces error message
  443.   - bug when extracting directories 'bad file name' removed
  444.   - tar$scrap now only has to be set when using compression
  445.  
  446. 1.0o
  447.   - RISC OS to UNIX file name conversion introduced
  448.     directory names may be converted to extensions,
  449.     '!' to '.', '/' to '_'
  450.   - new list file default '!tarlist'
  451.   - compress now called with I/O redirection, saves disk space and
  452.     I/O access time
  453.  
  454. 1.0n
  455.   - UNIX/RISC-OS time conversion rewritten: FP eliminated,
  456.     minor deviations corrected, over-/underflow check
  457.   - FSVars module no longer required
  458.  
  459. 1.0l-m
  460.   - system variable for compression scrap file tar$scrap
  461.   - system variables for compression and decompression commands
  462.     tar$compress, tar$decompress
  463.  
  464. 1.0h-i
  465.   - fixed more bugs with 's' option and introduced 'Z' option
  466.  
  467. 1.0g
  468.   - fixed bug with 's' option
  469.  
  470. 1.0f
  471.   - the 'r' option is now implemented
  472.   - the 'L' type discs are now implemented
  473.   - the 'M' option was dropped, multiple disk archives are now default
  474.     expect if writing a UNIX archive, or 'O' option is used
  475.   - new 'l' option introduced, files and options can now be specified
  476.     in a LIST file
  477.   - tar now prompts for 'discs' not 'volumes'
  478.  
  479. 1.0e
  480.   - first release into the public domain in 'eunet.micro.acorn'
  481.